Requirements:
-------------

Getting startet:
----------------

 Requirements:
  - Android 1.6? Tested with 2.3.6
  - Music files located in <DirRootExternal>/Music, which is most likely (?)
    /mnt/sdcard/Music
    Note the capital 'M'.

 Layout:
 The layout changes as you interact. However, at the bottom are some buttons
 that are always available, which currently are:
  - Play/Pause
  - Repeat mode
  - Skip
  - Quit

 You may switch layouts by slinding the display left or right (not working at
 the bottom area) between
   Folders <-> Current folder <-> player <-> search

 Folders:
   Shows any folder containing music (music in subfolders)
   Click to switch to current folder view

 Current folder
   Shows the content of the current folder
   Click on the folder item on top of the list to switch to Folder view
   Click on any song to play item. This will automatically switch to player view
   Long click on any song to invoke a popup menu with additional options.

Player
  Shows
   - The folder containing the current song. Click to switch to that folder.
   - The current song; Click to switch to the folder containing that song;
                       Long click to invoke a popup menu with additional options
   - Settings button; Click to opens setup popup dialog
   - Position/duration; Click to toggle between elapsed and remaining time
   - Info button
   - Position bar; Click to seek to certain position.

 Search
   Allowes you to search the playlist
   Click on folders to open them in current folder view
   Click on any song to play item. This will automatically switch to player view
   Long click on any song to invoke a popup menu with additional options.

Hidden features:
----------------

 - Install on sd-card. This makes partly sense, as Calaym relies on the music on
   the sd card. However, if installed on phone, you can start Calaym even if
   android's media scanner hasn't scanned apps on sd card yet. Calaym does not
   rely on the media library.
 - Calaym detects "ogg", "mp3", "mid"/".midi" and "flac" (flac files playback
   requires at least Android 3.1, otherwise flac files will be ignored)
 - when connecting (wired only?) headset, Calaym will fade in volume
 - when disconnecting (wired only?) headset, Calaym will pause
 - on headset (wired only?) button click Calaym will pause/unpause
 - on headset (wired only?) longer button press, Calaym will switch songs (fast
   crossfade)
 - on incoming/outgoing calls, Calaym will fade out, pause and resume afterwards
 - long clicking songs (in current directory, search list, or current song) will
   invoke a popup menu with additional options.
 - Multilanguage support (english / german currently included)

Pending features / To-do list:
------------------------------

 - last played songs? (view after / right of search?)
 - better default app handling (for headset button)
 - get rid of vertical scroll view?
 - add some more styles, also to make it easier to distinguish current view(s)
 - maybe add higher res images for additional controls
 - ignore activity pause/unpause when opening popups (context menu, info
   message, empty playlist message)?
 - Multithreading? (so playback continues when showing messages/popups)

Legal stuff:
------------

 - You can use this software under the terms of the User-friendly Open source
   License Version 1.00, published by Jan Vorel;
 - You can redistribute the official software packages under the terms of the
   User-friendly Distribution License Version 2.00, published by Jan Vorel.
 - Folder icons are from the "Tango Desktop Project" icon theme;
   http://tango.freedesktop.org/

Used libraries:
---------------

 - BroadcastReceiver 1.00 - Sends and receives Broadcasts in the Android
                            Operating System. (by XverhelstX - Tomas Verhelst)
 - Core              2.47 - Part of Basic4Android?
 - Dialogs           2.92 - Date, Time, Text, Number, Color, File and Custom
                            modal dialogs. (by Agraham - Andrew Graham)
 - id                1.00 - inputlist without radio controls (by Maximus /
                            thedesolatesoul ?)
 - IME               1.00 - Part of Basic4Android?
 - Phone             2.00 - Part of Basic4Android?
 - Reflection        2.40 - Reflection library for runtime creation and
                            manipulation of Java classes and object instances.
                            (by Agraham - Andrew Graham)

Permissions:
------------

 - Storage: modify/delete USB storage contents
   You can delete songs within Calaym.
 - Phone calls: Read phone status and ID
   Calaym will fade in/out on incoming/outgoing calls
 - Hardware controls: control vibrator
   Because Calaym does not use vibration when setting/updating notification
   icon/text?

By default some libraries want additional privileges, but these were disabled as
they should not be needed by Calaym.

Thanks:
-------
 - Marlene Vorel for letting me test on her tablet
 - Basic4Android, the community etc

Recent changes:
---------------

 1.00 beta 3:
  - Add: Long-pressing songs will show a popup menu, instead of just deleting
         that song (already added in beta 2?)
  - Add: Check if no music is found on startup / show message;
  - Del: Suppressed some permissions from libraries
  - Chg: Larger listitem height
  - Chg: Smaller search text box (height)
  - Add: Click on time (label) to switch between elapsed and remaining time;
         Default is now remaining time
  - Fix: Restoring last viewed directory properly
  - Chg: Fast crossfade when deleting
  - Fix: No skipping one song when deleting and repeat-all is set
  - Chg: flac support only if supported (android version 3.1 / newer).
  - Add: Support for .mid (and .midi) playback
  - Chg: Skip button now also on bottom bar
  - Chg: Tweaked headset (un)plug pausing / soft fade-in
  - Add: Settings button, plus setup dialog (not much in here, but it will grow
         eventually)
  - Add: Fixed volume option
  - Fix: When deleting paused songs, next song is loaded, but paused
  - Fix: When fading out to pause, and song end is reached while fading, next
         song is loaded, but paused.
  - Fix: Current song actions only available if only one song is active.
  - Add: Current song actions disabled if there was a song change was withing
         four seconds, other songs are still active (fading out), and some
         other extra checking.
  - Add: Some extra scroll checking when resuming activity
  - Fix: Quit icon shown instead of back icon
  - Add: Widget
  - Add: 'Enable rotation' option
  - Chg: Folder icon from tango theme
  - Add: Option to prevent media scanner from parsing music folders (.nomedia
         file)
  - Add: Media scanner updated when quitting if files were deleted
  - Add: Fading/crossfade indicator (icon)

 1.00 beta 2:
  - Fix: SEVERAL internal and minor visual BUGS
  - Add: Dual-views in landscape mode on large displays;
         (folders+files <-> files+player <-> player+search)
  - Add: Main 'buttons' now on panel with gray background
  - Add: Support for dual storage (sdcard/Music + sdcard/external_sd/Music)
         (As encountered on the Galaxy S Advance I9070P...)
  - Add: Search results are sorted

 1.00 beta 1:
   Almost everything I wanted the player to be, working and fully functional.
   Or so it appears. It has all features I considered essential, like fading,
   crossfading, search and some automatic playback features. Plus the mobile
   device related features.
